<html>
<head>
<meta http-equiv="Pragma" content="no-cache"/>
<meta http-equiv="Cache-Control" content="no-cache"/>
<meta http-equiv="Expires" content="-1" />
<title>Web Services - Sample 16: Control and use of the JavaScript API command buffer</title>

<style><!--
a{text-decoration:none;
  padding: 1px;
  background-color: #dddddd}
--></style>

<script src="json2.js"></script> 
<script src="pymol.js"></script>

<script type="text/javascript">

// This page assumes that PyMOL is running on localhost:8086

var pymol = new PyMOL('localhost',8086); // create PyMOL object instance for server of this page

var cmd = pymol.cmd; // assign a global symbol for the PyMOL cmd API

function process_chains(list) {
    for(var i=0;i<list.length;i++) {
        cmd.color("auto","chain "+list[i]);
    }
}

function part1() {
    pymol.setBufferMode('on');
    cmd.reinitialize();
    cmd.load("$PYMOL_PATH/test/dat/1tii.pdb", "atestname");
    cmd.show_as("cartoon");
    cmd.get_chains("polymer");
    jcmd = pymol.getBufferJSON();
    show_message(jcmd);
    jurl = pymol.getBufferURL();
    show_message(jurl);
    pymol.sendJSON(process_chains, jcmd);
    pymol.setBufferMode('off');
}

function show_message(msg) {
    document.getElementById('messages').innerHTML += "<LI>" + msg;
}
</script>

</head>
<body>

<h3>Web Services - Sample 16: Control and use of the JavaScript API command buffer</h3>

<a href="http://localhost:8086/apply/_quit?href">quit pymol</a>
(FireFox only: <a href="javascript:void(0)" onclick="window.open('view-source:' + location.href)">view page source</a>)
<p>
This example explains the use of the JavaScript API functions
setBufferMode, getBufferJSON, getBufferURL and sendJSON.
These allow you to:<UL>
<LI>set the command buffering mode on and off at any point in your JavaScript code.
<LI>retreive the current contents of the command buffer.
<LI>retrieve a URL containing the current command buffer.
<LI>send a JSON-encoded pymol command directly to PyMOL.
</UL>
</p>



<p>The setup of this example is just like sample 14:
we use the multi-origin scenario, providing the host and port for the PyMOL server.
In this example however, we call setBufferMode('on') in the function part1()
 instead of specifying the buffer mode when new PyMOL instance is created.
</p>

<pre>
var pymol = new PyMOL('localhost',8086); // create PyMOL object instance for server of this page

var cmd = pymol.cmd; // assign a global symbol for the PyMOL cmd API
</pre>

<p>As in sample14, the two part cascade is started by calling the function part1.
In this example's part1 function, the API function getBufferJSON() is called to
return the JSON-encoded list of pymol commands contained in the buffer.  This is simply
displayed on the web page without further processing.  Then the commmand is delivered
to PyMOL using the sendJSON(process_chains, jcmd) function call, causing the callback
to process_chains after the commands are executed by PyMOL.
<pre>

function part1() {
    pymol.setBufferMode('on');
    cmd.reinitialize();
    cmd.load("$PYMOL_PATH/test/dat/1tii.pdb", "atestname");
    cmd.show_as("cartoon");
    cmd.get_chains("polymer");
    jcmd = pymol.getBufferJSON();
    show_message(jcmd);
    jurl = pymol.getBufferURL();
    show_message(jurl);
    pymol.sendJSON(process_chains, jcmd);
    pymol.setBufferMode('off');
}
</pre>

<p>Start this example by running <a href="javascript:part1()">part1</a>.
<BR>
The getBufferJSON and getBufferURL results appear below:
</p>

<!--  place to put message, as from getBufferJSON
-->
<p>
<div id=messages style="border-style: solid">
</div>
</p>

<!-- one purpose of this IFRAME is to launch PyMOL via the PWG
  -- helper mechanism
  -- It is also used as target for method4 link and to display
 --  results of getBufferJSON and getBufferURL
-->

<iframe src="start8086.pwg" name=dumper
 width="0" height="0" frameborder="0"
 marginheight="0" marginwidth="0"
 scrolling="auto"></iframe>

<p>
Possible uses for getBufferJSON and getBufferURL:
<BR>
Sample 13 showed how a simple pymol command can be used with jQuery.  In that example,
the URL supplied to jQuery's getJSON function was a fixed string containing the pymol load command.
<pre>
$(document).ready(function() {

  $("a[name=load]").click(function() {
    try {
      $.getJSON(host+"/apply/pymol.cmd.load?filename=$PYMOL_PATH/test/dat/pept.pdb&_callback=?", callback1);
    } catch (e) {
      alert(e);
    }
    return false; // causes the HREF to not load a new page
  });
});
</pre>
Multiple pymol commands can be easily used with jQuery by setting command buffering on,
issuing any JavaScript API pymol.cmd commands, and getting a valid URL using getBufferURL.
This URL be used with jQuery's getJSON in a way analogous to sample 13.
This frees you from having to construct individual pymol command strings,
or to encode them into a valid URL.
<pre>
$(document).ready(function() {

// this function assumes that a (global) pymol instance has already been created
//  and that there are already some commands in the command buffer.
  $("a[name=load]").click(function() {
    try {
      $.getJSON(host+pymol.getBufferURL()+"&_callback=?", callback1);
    } catch (e) {
      alert(e);
    }
    return false; // causes the HREF to not load a new page
  });
});
</pre>
</body>
</html>
